fix(codegen): pin openapi-generator 7.25.0 and guard codegen in CI (PER-16500) - #135

Summary

• Pins openapi-generator-cli to 7.25.0 (was 6.2.1). Generator 6.2.1 can't read the API's OpenAPI 3.1 spec: generate-openapi-client exits 0 and emits an all-any client (generate-openapi-client silently emits an all-any client: pinned generator 6.2.1 cannot read the now-3.1 spec #130).
• Adds scripts/check-codegen.mjs (yarn check:codegen). It generates a client from a committed 3.1 spec fixture, using the pinned generator and the options from generate-openapi-client. It fails if models degrade to any or if specific property types change.
• Adds scripts/check-codegen.spec.mjs (yarn test:codegen): 43 AVA tests for the guard's failure paths. They don't need Java.
• Adds a codegen-guard CI job: SHA-pinned actions, a read-only token, no secrets, so it works on fork PRs. Also sets workflow-level permissions: contents: read.
• Doesn't regenerate src/openapi/. That is PER-16500's semver-major follow-up.

Linear

• Part of PER-16500: Node SDK: restore OpenAPI client regeneration (generator 6.2.1 can't read the 3.1 spec) and ship the missing role extends types

Closes #130.

Details

Generator pin (openapitools.json)

• 7.25.0 is the current release on Maven Central (checked 2026-09-29).
• It supports the four typescript-axios options the generate script uses: useSingleRequestParameter, withSeparateModelsAndApi, apiPackage and modelPackage.
• Its output for the fixture (394 files) compiles with the repo's TypeScript 4.9.5 and tsconfig.
• 7.25.0 still logs that OpenAPI 3.1 support is in beta.

Guard (scripts/check-codegen.mjs)

• Reads the generator version from openapitools.json and the options from generate-openapi-client. It rejects options it can't reproduce, and it works from any working directory.
• Generates into a temporary directory and removes it on both success and failure.
• Fails when:
  • the generator's completion metadata (VERSION, FILES) doesn't match the pin or the files on disk;
  • any model has an unexpected bare any (20 named free-form fields are allowed);
  • one of 11 exact property shapes changes. These include RoleCreate.extends, ResourceRoleCreate.extends and nullable 3.1 unions, which two synthetic probe schemas cover.
• Failure messages name the pinned generator, the file and the property.
• With the old 6.2.1 pin, the guard fails with 1,749 shape errors.

Fixture (src/tests/codegen/fixtures/)

openapi-3.1.0.json is a snapshot of the API spec (329 schemas, 160 paths) plus the CodegenProbe and CodegenProbeInner schemas. The README records the source, the known limitations and the refresh steps.

CI (.github/workflows/ci.yaml)

• The new codegen-guard job runs checkout (persist-credentials: false), setup-node (Node 22, yarn cache) and setup-java (Temurin 17). All three are pinned to commit SHAs with version comments.
• It then runs yarn install --frozen-lockfile --ignore-scripts, yarn test:codegen and yarn check:codegen, with a 15-minute timeout.
• yarn test and yarn lint also run the new tests and lint through test:* and lint:*.
• Workflow-level permissions: contents: read: the existing test-and-lint job only reads the repo.

Testing

• yarn build: passes
• yarn lint: 0 errors (7 existing warnings)
• yarn test:unit: 48 passed
• yarn test:module-imports: 9 passed
• yarn test:codegen: 43 passed
• yarn check:codegen: passes with 7.25.0 (346 models)
• actionlint: clean
• zizmor: nothing in codegen-guard. The remaining findings are in the existing test-and-lint job, which ci: pin actions to SHA and run full test suite on PRs #131 addresses.

Notes

• ci.yaml conflicts textually with ci: pin actions to SHA and run full test suite on PRs #131's rewrite, which is being folded into permitio 3.0.0: refactor SDK APIs, tests, and release validation #134. Whichever lands second should keep this job as-is.
• Known limits, documented in the fixture README:
  • an untyped const still becomes any;
  • the API's nonstandard auth schema types produce an empty Secret interface;
  • drift in the live spec isn't checked, because the fixture is a snapshot.
• Follow-ups under PER-16500:
  • regenerate src/openapi/ with 7.25.0 in a semver-major release;
  • fix the backend Secret schema;
  • update the @openapitools/openapi-generator-cli wrapper from 2.7.0 to the current version.

Original change by @Kyzgor; the guard hardening, generator bump and CI commits were added by the maintainers.

🤖 Generated with Claude Code

https://claude.ai/code/session_01PSoip6dghQ62bLQ6GBMwTA